fix(extension): inline agent content instead of path stubs in packaged plugins by stablegenius49 · Pull Request #907 · microsoft/hve-core

stablegenius49 · 2026-03-06T01:30:57Z

Pull Request

Description

When plugins are packaged in non-symlink environments (e.g., Windows without Developer Mode, or when Copilot CLI installs plugins), agent files were being written as single-line relative path references instead of actual YAML frontmatter content. This caused Copilot CLI to fail with 'frontmatter is malformed' errors on all agent files.

Root Cause

The New-PluginLink function was writing text stubs containing relative paths when symlinks were not supported. The Copilot CLI expects agent .md files to begin with valid YAML frontmatter (--- delimited block with at least a description field), but received single-line path strings instead.

Fix

Changed New-PluginLink to copy the actual file content when symlinks are not supported, ensuring agent files have valid YAML frontmatter in installed plugins.

Before:

else {
    [System.IO.File]::WriteAllText($DestinationPath, $relativePath)
}

After:

else {
    # Copy the actual file content instead of writing a path reference
    # This ensures agent files have valid YAML frontmatter in installed plugins
    Copy-Item -Path $SourcePath -Destination $DestinationPath -Force
}

Related Issue(s)

Fixes #785

Type of Change

Select all that apply:

Code & Documentation:

Bug fix (non-breaking change fixing an issue)
New feature (non-breaking change adding functionality)
Breaking change (fix or feature causing existing functionality to change)
Documentation update

Infrastructure & Configuration:

AI Artifacts:

Reviewed contribution with prompt-builder agent and addressed all feedback
Copilot instructions (.github/instructions/*.instructions.md)
Copilot prompt (.github/prompts/*.prompt.md)
Copilot agent (.github/agents/*.agent.md)
Copilot skill (.github/skills/*/SKILL.md)

Other:

Script/automation (.ps1, .sh, .py)
Other (please describe):

Testing

This fix ensures:

Agent files have valid YAML frontmatter when installed via copilot plugin install
Commands, instructions, and skills continue to work correctly
Plugin packaging works in both symlink and non-symlink environments

Validation

Local testing shows agent files now contain actual content instead of path references
The fix maintains the same directory structure and behavior for symlink environments
No changes to symlink behavior when supported

Checklist

Required Checks

Documentation is updated (if applicable)
Files follow existing naming conventions
Changes are backwards compatible (if applicable)
Tests added for new functionality (if applicable)

Required Automated Checks

The following validation commands must pass before merging:

Markdown linting: npm run lint:md
Spell checking: npm run spell-check
Frontmatter validation: npm run lint:frontmatter
Skill structure validation: npm run validate:skills
Link validation: npm run lint:md-links
PowerShell analysis: npm run lint:ps
Plugin freshness: npm run plugin:generate

Security Considerations

This PR does not contain any sensitive or NDA information
Any new dependencies have been reviewed for security issues
Security-related scripts follow the principle of least privilege

Additional Notes

When plugins are packaged in non-symlink environments (e.g., Windows without Developer Mode), agent files were being written as single-line relative path references instead of actual YAML frontmatter content. This caused Copilot CLI to fail with 'frontmatter is malformed' errors on all agent files. The fix changes New-PluginLink to copy actual file content when symlinks are not supported, ensuring agent files have valid YAML frontmatter in installed plugins. Fixes microsoft#785 Co-Authored-By: Stable Genius <noreply@anthropic.com>

WilliamBerryiii · 2026-03-06T03:45:25Z

@ Maintainers - please hold on this until we can fully confirm the backing issue is as described and we're sure of the approach. I'm on a windows box and can test this, but won't have time for a bit. @peterbryntesson .... if you have access to windows bare metal ... this would be a cool one to run to ground to make sure this fix is correct and we can generate these files correctly (e.g. the fake symlinks) without having to run the regenerate plugins in Admin via powershell.

WilliamBerryiii · 2026-03-06T04:50:41Z

@stablegenius49 - please sign the LCA

WilliamBerryiii · 2026-03-06T18:29:34Z

@stablegenius49 - I'm going to take over this branch and complete the work here so that you contribution marker remains. I really appreciate you taking a run at this one and your solution is close, but needs some additions. Should have this completed and tested today, but not sure I'll be able to cut a release until next week due to the other changes we've already merged down into main.

WilliamBerryiii · 2026-03-07T04:48:16Z

We've updated the PR description to align with the current pull request template. All original content has been preserved and relocated into the appropriate template sections. No action needed on your end — though you're welcome to review the updated description and fill in any remaining sections (testing details, checklist confirmations, etc.) at your convenience.

stablegenius49 · 2026-03-08T07:31:59Z

@microsoft-github-policy-service agree

WilliamBerryiii · 2026-03-08T22:32:04Z

PR Compliance Update — Added the missing (extension) scope to the PR title to align with the project's Conventional Commits convention:

Before: fix: inline agent content instead of path stubs in packaged plugins
After: fix(extension): inline agent content instead of path stubs in packaged plugins

The PR body and Fixes #785 reference were already correctly formatted. Thank you for the contribution! 🙏

WilliamBerryiii · 2026-03-09T23:50:49Z

Per the linked issue, I'm going to revert this back to a draft until we have some resolution from the CLI team on how to make all this work correctly.

chaosdinosaur

Review of PR #907 — inline agent content instead of path stubs in packaged plugins.

The core fix is sound: replacing text-stub path references with actual file content ensures Copilot CLI can parse agent YAML frontmatter in non-symlink environments. However, the change has several downstream impacts that need attention before merging:

High priority:

Repair-PluginSymlinkIndex becomes a silent no-op since its text-stub detection heuristic will never match full file content
Copy-Item without -Recurse won't work correctly for the shared directory sources (docs/templates, scripts/lib) passed at line 657

Medium priority:

The existing test 'Writes text stub when SymlinkCapable is false' will fail and needs updating

Low priority:

Dead $relativePath computation in the non-symlink branch
Stale comments in Generate-Plugins.ps1 referencing text stubs

5 inline comments with details and suggestions.

chaosdinosaur · 2026-04-22T19:50:38Z

+        # This ensures agent files have valid YAML frontmatter in installed plugins
+        Copy-Item -Path $SourcePath -Destination $DestinationPath -Force
    }
 }



⚠️ Functional Correctness — High: Repair-PluginSymlinkIndex is now a silent no-op

Repair-PluginSymlinkIndex detects text stubs by checking for files < 500 bytes whose content matches ^\.\./ (a relative path starting with ../). With New-PluginLink now using Copy-Item, the non-symlink fallback produces full file content that will never match this heuristic — making the entire function a silent no-op.

The caller in Generate-Plugins.ps1 (line 299) still invokes it and logs "entries fixed", but nothing will ever be fixed.

Since copied files should be committed as regular files (not mode 120000 symlinks), this function likely needs to be removed entirely, along with its call site and the comment-based help that still references "text stubs containing relative paths." If git index mode repair is still needed for some other reason, the detection logic needs reworking.

chaosdinosaur · 2026-04-22T19:50:48Z

+        # This ensures agent files have valid YAML frontmatter in installed plugins
+        Copy-Item -Path $SourcePath -Destination $DestinationPath -Force
    }


⚠️ Functional Correctness — High: Copy-Item on directory sources lacks -Recurse

New-PluginLink is also called for shared directories (docs/templates, scripts/lib) at line 657 in Write-PluginDirectory. Without -Recurse, Copy-Item on a directory source copies only the top-level directory, not its contents. The old WriteAllText created a single file acting as a text-based symlink — Copy-Item on a directory is fundamentally different.

Suggestion: Add directory detection:

if (Test-Path -Path $SourcePath -PathType Container) { Copy-Item -Path $SourcePath -Destination $DestinationPath -Recurse -Force } else { Copy-Item -Path $SourcePath -Destination $DestinationPath -Force }

Or keep directory sources on the symlink-only path and limit Copy-Item to file sources.

chaosdinosaur · 2026-04-22T19:50:57Z

+        # Copy the actual file content instead of writing a path reference
+        # This ensures agent files have valid YAML frontmatter in installed plugins
+        Copy-Item -Path $SourcePath -Destination $DestinationPath -Force
    }


🔍 Functional Correctness — Medium: Existing test will fail

The test 'Writes text stub when SymlinkCapable is false' in scripts/tests/plugins/PluginHelpers.Tests.ps1 (line 233) asserts the destination file content equals the computed relative path. After this change, the destination contains the source file's actual content, not the relative path. This test will break.

Suggestion: Update the test to validate the new copy behavior:

It 'Copies file content when SymlinkCapable is false' { $src = Join-Path $script:linkRoot 'src-stub.txt' Set-Content -Path $src -Value 'content' -NoNewline $dest = Join-Path $script:linkRoot 'dest-stub.txt' New-PluginLink -SourcePath $src -DestinationPath $dest Test-Path $dest | Should -BeTrue $destContent = [System.IO.File]::ReadAllText($dest) $destContent | Should -Be 'content' }

chaosdinosaur · 2026-04-22T19:51:15Z

    else {
-        [System.IO.File]::WriteAllText($DestinationPath, $relativePath)
+        # Copy the actual file content instead of writing a path reference
+        # This ensures agent files have valid YAML frontmatter in installed plugins


💡 Code Quality — Low: Dead code — $relativePath unused in non-symlink branch

$relativePath is computed unconditionally (line 499) but only the symlink branch uses it now. Consider moving it inside the if ($SymlinkCapable) block to avoid dead code.

chaosdinosaur · 2026-04-22T19:51:26Z

💡 Documentation — Low: Generate-Plugins.ps1 comments reference obsolete text-stub behavior

The comment at line 296 in Generate-Plugins.ps1 reads "Fix git index modes for text stubs on non-symlink systems" and the conditional block invokes Repair-PluginSymlinkIndex. Both reference the old text-stub pattern that this PR eliminates. Should be updated or removed consistent with the resolution for Repair-PluginSymlinkIndex.

stablegenius49 requested a review from a team as a code owner March 6, 2026 01:30

WilliamBerryiii changed the title ~~fix: inline agent content instead of path stubs in packaged plugins~~ fix(extension): inline agent content instead of path stubs in packaged plugins Mar 8, 2026

WilliamBerryiii marked this pull request as draft March 9, 2026 23:51

chaosdinosaur reviewed Apr 22, 2026

View reviewed changes

Conversation

stablegenius49 commented Mar 6, 2026 • edited by WilliamBerryiii Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

Description

Root Cause

Fix

Related Issue(s)

Type of Change

Testing

Validation

Checklist

Required Checks

Required Automated Checks

Security Considerations

Additional Notes

Uh oh!

WilliamBerryiii commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

WilliamBerryiii commented Mar 6, 2026

Uh oh!

WilliamBerryiii commented Mar 6, 2026

Uh oh!

WilliamBerryiii commented Mar 7, 2026

Uh oh!

stablegenius49 commented Mar 8, 2026

Uh oh!

WilliamBerryiii commented Mar 8, 2026

Uh oh!

WilliamBerryiii commented Mar 9, 2026

Uh oh!

chaosdinosaur left a comment

Choose a reason for hiding this comment

Uh oh!

chaosdinosaur Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

chaosdinosaur Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

chaosdinosaur Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

chaosdinosaur Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

chaosdinosaur Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stablegenius49 commented Mar 6, 2026 •

edited by WilliamBerryiii

Loading

WilliamBerryiii commented Mar 6, 2026 •

edited

Loading